package org.marketlive.system.config;

/**
 * Retrieves a single branch or leaf or the set of all leaves and branches that are
 * attached to this branch. 
 */

/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/

public interface IConfigurationBranch extends IConfigurationNode {

    /**
     * Returns <code>IConfigurationBranch</code> for the given branch.
     * @param name of the branch to retrieve
     * @return <code>IConfigurationBranch</code> of given branch
     * @throws IllegalArgumentException
     */
    IConfigurationBranch getBranch(String name) throws IllegalArgumentException;

    /**
     * Returns <code>IConfigurationLeaf</code> for the given leaf.
     * @param name of the leaf to retrieve
     * @return <code>IConfigurationLeaf</code> of the given leaf
     * @throws IllegalArgumentException
     */
    IConfigurationLeaf getLeaf(String name) throws IllegalArgumentException;

    /**
     * Returns an array of <code>IConfigurationBranch</code>es containing sub-branches 
     * to the given branch
     * @return <code>IConfigurationBranch</code>[] array containing sub-branches 
     */
    IConfigurationBranch[] getBranches();

    /**
     * Returns an array of <code>IConfigurationLeaf</code>s .
     * @return <code>IConfigurationLeaf</code>[] array containing leaves.
     */
    IConfigurationLeaf[] getLeaves();

    /**
     * Returns the value of the given configuration leaf. 
     *
     * @param name the leaf variable name, including the full path, starting at the root, whose value to return
     * @return value of the given configuration leaf
     */
    public String getAsString(String name);
}
